Skip to content

Add built-in tracing and metrics (ActivitySource/Meter) - #1857

Open
YoussefElshemi wants to merge 4 commits into
sshnet:developfrom
YoussefElshemi:native-telemetry
Open

YoussefElshemi wants to merge 4 commits into
sshnet:developfrom
YoussefElshemi:native-telemetry

Conversation

@YoussefElshemi

Copy link
Copy Markdown

Closes #1854

Adds built-in tracing and metrics using System.Diagnostics ActivitySource and Meter, both named Renci.SshNet. OpenTelemetry (or any other listener) picks them up with:

builder.Services.AddOpenTelemetry()
    .WithTracing(t => t.AddSource("Renci.SshNet"))
    .WithMetrics(m => m.AddMeter("Renci.SshNet"));

When nothing is listening, SshNetTelemetry.IsEnabled is checked first, so no spans, tags or timestamps are created.

What is instrumented

Each operation produces a Client span named {protocol} {operation} (e.g. sftp UploadFile) and a ssh.client.operation.duration histogram measurement (seconds).

  • Connect for SshClient, SftpClient and NetConfClient (ssh / sftp / netconf), sync and async
  • SFTP: UploadFile, DownloadFile, ListDirectory, ChangeDirectory, ChangePermissions, CreateDirectory, DeleteDirectory, DeleteFile, Delete, RenameFile, SymbolicLink, Get, Exists, GetStatus, GetAttributes, SetAttributes — sync, async and Begin/End where they exist
  • SshCommand execution (ssh Execute)

Not instrumented:

  • SCP (ScpClient is unchanged, as discussed in the issue; its Connect still goes through BaseClient and shows up as ssh Connect)
  • Stream-based APIs (Open*, ReadAll*, WriteAll*, AppendAll*), since a span would only cover opening the handle, not the I/O
  • Command text, as it may contain secrets

Attributes

Attribute Source Span Metric
network.protocol.name semconv ✓ ✓
server.address, server.port semconv ✓ ✓
error.type semconv ✓ ✓
file.path semconv ✓ (high cardinality)
ssh.operation.name custom ✓ ✓
sftp.transfer.bytes custom ✓
ssh.command.exit_code custom ✓

There is no SSH/SFTP semantic convention yet, so the custom names should be treated as experimental. Failed operations set span status to Error and record error.type (exception type name). Exists returning false is not an error.

Notes for review

  • SshCommand.ExecuteAsync isn't an async method, so it restores Activity.Current after starting the span; otherwise the caller would continue inside the command's span.
  • The command span is ended before the TaskCompletionSource is completed, so it has ended by the time awaiters resume. It is also ended if the command is disposed mid-run.
  • Delete and ChangePermissions call Get internally, so their spans have a child Get span.
  • New dependency: System.Diagnostics.DiagnosticSource 8.0.1 on net462/netstandard2.0 only (newer TFMs have it in-box).
  • Public Connect/ConnectAsync in BaseClient now wrap private ConnectCore/ConnectCoreAsync; no public API changes.

Testing

  • Release build clean on all targets
  • Unit tests pass (net10.0)
  • New TelemetryTests integration tests (spans, parenting, attributes, durations, errors, command timeout/exit code) pass on net48, net8.0, net9.0 and net10.0
  • Existing SFTP / SshClient / connectivity integration tests pass (net10.0)
  • Also checked the output manually against the .NET Aspire dashboard

This change was developed with AI assistance. I have reviewed and tested all of it.

Emits spans and an ssh.client.operation.duration histogram from an
ActivitySource/Meter named "Renci.SshNet" for Connect, SFTP upload,
download and list, and SshCommand execution. Nothing is allocated or
read when there are no listeners.
The command span is now ended before the task completes, so it has
ended by the time awaiters resume, and a command disposed mid-run
also ends its span. Adds integration tests for SFTP, connect and
command telemetry.
Adds spans and durations for ChangeDirectory, ChangePermissions,
CreateDirectory, DeleteDirectory, DeleteFile, Delete, RenameFile,
SymbolicLink, Get, Exists, GetStatus, GetAttributes and SetAttributes,
sync and async. Exists reporting a missing path is not an error.

Reverts the SCP protocol name, as SCP is a legacy protocol.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Timeout telemetry can leak command passwords or tokens to tracing backends, while cancellation races and unrecorded directory-close failures produce inaccurate span outcomes.

3 open issues
What changed in this PR

Adds built-in tracing and duration metrics to SSH.NET, addressing #1854 through an ActivitySource and Meter named Renci.SshNet that work with OpenTelemetry and other listeners.

Changes:

  • Instruments connection setup, SFTP operations, and SSH command execution.
  • Adds shared telemetry handling for operation attributes, errors, and durations, with a no-listener guard.
  • Adds compatibility dependencies and integration tests for spans, parenting, metrics, and failures.
File Description
test/​Renci.SshNet.IntegrationTests/​TelemetryTests.cs Tests telemetry attributes, parenting, durations, and errors.
src/​Renci.SshNet/​SshNetTelemetry.cs Defines shared tracing and metric infrastructure.
src/​Renci.SshNet/​SshCommand.cs Tracks command execution and completion.
src/​Renci.SshNet/​SftpClient.cs Instruments transfers, directory listings, and metadata operations.
src/​Renci.SshNet/​Renci.SshNet.csproj Adds DiagnosticSource for older target frameworks.
src/​Renci.SshNet/​NetConfClient.cs Labels connection telemetry as netconf.
src/​Renci.SshNet/​BaseClient.cs Instruments synchronous and asynchronous connections.
Directory.Packages.props Pins the DiagnosticSource dependency version.

Review effort: Balanced


public void SetError(Exception exception)
{
SetError(exception.GetType().FullName!, exception.Message);
Comment on lines +751 to +753
// The operation spans the whole enumeration. C# does not allow yield
// inside try/catch, so errors are recorded around each request instead.
using var operation = StartOperation("ListDirectory", path);
Comment on lines +595 to +598
var operation = Interlocked.Exchange(ref _operation, value: null);
if (operation is null)
{
return;

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Proposal: built-in tracing and metrics via ActivitySource/Meter

2 participants